home *** CD-ROM | disk | FTP | other *** search
/ Linux Cubed Series 7: Sunsite / Linux Cubed Series 7 - Sunsite Vol 1.iso / system / manual-p / man_db-m.5 / man_db-manual.cat
Text File  |  1995-04-18  |  67KB  |  2,113 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.    mmaann__ddbb--22..33..xx -- tthhee ddaattaabbaassee ccaacchheedd mmaannuuaall ppaaggeerr ssuuiittee
  22.  
  23.  
  24.          _G_r_a_e_m_e _W_. _W_i_l_f_o_r_d _<_e_e_p_2_g_w_@_e_e_._s_u_r_r_e_y_._a_c_._u_k_>
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.     This  document  describes the setup, maintenance and
  32.     use of a generic online manual page system with spe-
  33.     cial  reference  to  man_db-2.3.x  and it's advanced
  34.     features.
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71. mmaann__ddbb--22..33..xx             mmaannuuaall vv00..55          AApprriill 1188,, 11999955
  72.  
  73.  
  74. UUNNIIXX is a registered trademark of the X/Open Company, Ltd.
  75. NFS is a registered trademark of Sun Microsystems, Inc.
  76. PostScript is a registered trademark of Adobe in the  United
  77. States.
  78.  
  79. The general conventions used throughout this manual include
  80.  
  81.  +o file names and paths in _i_t_a_l_i_c, eg.  _/_u_s_r_/_m_a_n.
  82.  +o variable   strings  (usually  path  components)  enclosed
  83.    within <> and in _i_t_a_l_i_c, eg.  _<_s_e_c_>,
  84.  +o program names in bboolldd, eg.  mmaann.                   _____
  85.  +o comman_d_s__t_h_a_t__c_a_n_ be typed at a shell prompt in a  |_b_o_x_|_,
  86.    eg.  |_m_a_n__f_o_o_b_a_r_|_.
  87.  +o environment variables denoted as follows: $EENNVV__VVAARR
  88.  
  89.  
  90.  
  91.  
  92.  
  93.  
  94.  
  95.  
  96.  
  97.  
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108. Copyright (C) 1995 Graeme W. Wilford
  109.  
  110. Permission is granted to make and distribute verbatim copies
  111. of this manual provided the copyright notice and  this  per-
  112. mission notice are preserved on all copies.
  113.  
  114. Permission  is  granted to copy and distribute modified ver-
  115. sions of this manual under the conditions for verbatim copy-
  116. ing, provided that the entire resulting derived work is dis-
  117. tributed under the terms of a notice identical to this  one.
  118.  
  119. Permission is granted to copy and distribute translations of
  120. this manual into another language, under  the  above  condi-
  121. tions for modified versions, except that this permission no-
  122. tice may be stated in a translation approved  by  the  copy-
  123. right holder.
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137. mmaann__ddbb--22..33..xx             mmaannuuaall vv00..55          AApprriill 1188,, 11999955
  138.  
  139.  
  140. 11..  IInnttrroodduuccttiioonn
  141.  
  142. 11..11..  mmaann__ddbb--22..33..xx
  143.  
  144. man_db-2.3.x  is a package that is designed to provide users
  145. with online information in a fast and friendly manner  while
  146. at the same time offering flexibility to the system adminis-
  147. trator.
  148.  
  149. It is made up of several user programs:
  150.          ++oo mmaann       - an interface to the on-line reference manuals
  151.          ++oo wwhhaattiiss    - search the manual page names
  152.          ++oo aapprrooppooss   - search the manual page names and descriptions
  153.          ++oo mmaannppaatthh   - determine search path for manual pages
  154. several maintenance programs:
  155.          ++oo mmaannddbb     - create or update the manual page index caches
  156.          ++oo ccaattmmaann    - create or update the pre-formatted manual pages
  157. and a special pre-formatter that knows about compressed manual pages
  158.          ++oo zzssooeelliimm   - satisfy .so requests in roff input
  159.  
  160.  
  161. In addition to these compiled programs, there are two  shell
  162. scripts,  mmkkccaattddiirrss  and cchheecckkmmaann in the _t_o_o_l_s subdirectory.
  163. These scripts aid the creation of cat directories and  check
  164. for duplicated manual pages, respectively.
  165.  
  166. The following manual pages are provided with this package to
  167. explain correct format and usage.  mmaann(1), wwhhaattiiss(1),  aapprroo--
  168. ppooss(1),  mmaannppaatthh(1),  mmaannppaatthh(5),  mmaannddbb(8),  ccaattmmaann(8)  and
  169. zzssooeelliimm(1).
  170.  
  171. 11..11..11..  TThhee ccoonncceepptt
  172.  
  173. man_db-2.3.x originally started out life  as  program  suite
  174. man-1.1B, written by John W.  Eaton <jwe@che.utexas.edu> and
  175. maintained by Rik Faith <faith@cs.unc.edu> to which  support
  176. proposed  by the newly formed FFSSSSTTNNDD committee regarding cat
  177. directories was added.
  178.  
  179. Since then,  man_db-2.3.x's  most  innovative  feature:  the
  180. database cache scheme1 has been significantly developed. The
  181. basic idea was to reduce manual page search times to a mini-
  182. mum.  The  following  piece  of  text  is  included from the
  183. man_db-2.2 distribution:
  184.  
  185.     The theory: If you go to a library to  take  a  book
  186.     out, what do you do?
  187. ____________________
  188.    1 originally conceived after observing the actions of the
  189. perl based manual pager suite, man-pl written by Tom  Chris-
  190. tiansen <tchrist@convex.com>
  191.  
  192.  
  193.  
  194.  
  195.                               11
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203. mmaann__ddbb--22..33..xx             mmaannuuaall vv00..55          AApprriill 1188,, 11999955
  204.  
  205.  
  206.     a)  Go  and  look  where  it  might  be  on a micro-
  207.     fiche/terminal, take a look
  208.        where it is supposed to be on the shelf, and then
  209.     go look at the new
  210.        arrivals if it's not where it's supposed to be?
  211.  
  212.     OR
  213.  
  214.     b)  Start at one end of the ground floor, look along
  215.     every bookshelf
  216.        until you've completed that floor, then go  up  a
  217.     level and start again
  218.        until you've found what you're looking for?
  219.  
  220.  
  221. Since  then  the  database iinnddeexx scheme has evolved greatly.
  222. Every manual page and stray cat page on the system is regis-
  223. tered  in  an  iinnddeexx  database  cache  which  stores various
  224. details about the file including the timestamp, the location
  225. and  the whatis2 information. This information is kept up to
  226. date by mmaann which looks for filesystem changes each time  it
  227. is invoked.
  228.  
  229. 11..22..  TThhee mmaannuuaall ppaaggee ssyysstteemm
  230.  
  231. The  simplest  manual  page system will have a single manual
  232. page hierarchy.  This will typically be
  233.  
  234.      _/_u_s_r_/_m_a_n
  235.  
  236. beneath which will be several  subdirectories  of  the  form
  237. _m_a_n_<_s_e_c_> where _<_s_e_c_> is 11, 22, 33, 44, 55, 66, 77 or 88.  These are
  238. referred to as _s_e_c_t_i_o_n_s of the manual. Others may exist  and
  239. they are not restricted to single character names. eg.
  240.  
  241.      _/_u_s_r_/_m_a_n_/_m_a_n_f_o_o
  242.  
  243. is  a  valid  section  subdirectory.   Other common sections
  244. include 99, nn, ll, pp and oo.
  245.  
  246. Within these section subdirectories reside the manual  pages
  247. themselves. Their filenames follow the pattern
  248.  
  249.      _/_u_s_r_/_m_a_n_/_m_a_n_<_s_e_c_>_/_<_n_a_m_e_>_._<_s_e_c_>_<_e_x_t_>
  250.  
  251. where in most cases _<_e_x_t_> is an empty string.  An example is
  252. manual page ccpp
  253.  
  254.  
  255. ____________________
  256.    2 one line description of the manual page
  257.  
  258.  
  259.  
  260.  
  261.                               22
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269. mmaann__ddbb--22..33..xx             mmaannuuaall vv00..55          AApprriill 1188,, 11999955
  270.  
  271.  
  272.      _/_u_s_r_/_m_a_n_/_m_a_n_1_/_c_p_._1
  273.  
  274. which resides in _s_e_c_t_i_o_n 11 and has no special _e_x_t_e_n_s_i_o_n.
  275.  
  276. 11..33..  SSeeccttiioonnss ooff tthhee mmaannuuaall
  277.  
  278. The manual is split up into sections to ease access  and  to
  279. cater  for manual pages that share the same name. It is com-
  280. mon for a program and function to share the same name.  kkiillll
  281. is a good example.  This is both a program which can be used
  282. to send a process a signal and an operating system call with
  283. similar  functionality.  Their manual pages are stored under
  284. sections 11 and 22 respectively.  Thus, sections are  used  to
  285. separate out the program manual pages from the function man-
  286. ual pages and so on.  The table below shows the _s_e_c_t_i_o_n num-
  287. bers  of the manual followed by the types of pages they con-
  288. tain.
  289.  
  290.  
  291. +--------+------------------------------------------------------+
  292. |Section |                   Section contents                   |
  293. +--------+------------------------------------------------------+
  294. |   1    | user executable programs or shell commands           |
  295. |   2    | system calls (functions provided by the kernel)      |
  296. |   3    | library calls (functions within system libraries)    |
  297. |   4    | special files (usually found in _/_d_e_v)                |
  298. |   5    | file formats and conventions eg. _/_e_t_c_/_p_a_s_s_w_d         |
  299. |   6    | games                                                |
  300. |   7    | macro packages and conventions eg. mmaann(7), ggrrooffff(7). |
  301. |   8    | system administration commands                       |
  302. |   9    | kernel routines [Non standard]                       |
  303. |   n    | new [obsolete]                                       |
  304. |   l    | local [obsolete]                                     |
  305. |   p    | public [obsolete]                                    |
  306. |   o    | old [obsolete]                                       |
  307. +--------+------------------------------------------------------+
  308.  
  309.  
  310. 11..44..  TThhee ffoorrmmaatt ooff mmaannuuaall ppaaggeess
  311.  
  312. The format in which manual pages are stored  is  NNRROOFFFF/TTRROOFFFF
  313. or   more  generally  ROFF.   This  is  a  typesetter  style
  314. language3 which requires formatting before being viewed.  In
  315. fact some manual pages require pre-format processing to cor-
  316. rectly format tables or equations.
  317.  
  318. If the page is to be viewed on screen in a text environment,
  319. NNRROOFFFF is used as the primary formatter. If the page is to be
  320. printed or displayed in a graphical  environment,  TTRROOFFFF  is
  321. ____________________
  322.    3 similar in some aspects to TTeeXX
  323.  
  324.  
  325.  
  326.  
  327.                               33
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335. mmaann__ddbb--22..33..xx             mmaannuuaall vv00..55          AApprriill 1188,, 11999955
  336.  
  337.  
  338. used. Traditionally, TTRROOFFFF formatted files for a CC//AA//TT (Com-
  339. puter aided Typesetter) which is now obsolete.
  340.  
  341. The GGNNUU ROFF (GGRROOFFFF4) suite of programs offer  a  choice  of
  342. output  types including XX, ddvvii and ppoossttssccrriipptt.  When config-
  343. uring man_db-2.3.x, the preference is to  use  GGRROOFFFF  rather
  344. than TTRROOFFFF.
  345.  
  346. 11..55..  AArrgguummeennttss ttoo ccoonnffiigguurree
  347.  
  348. To  allow  the  configuration program, ccoonnffiigguurree, to be non-
  349. interactive, it can be passed various options to  alter  the
  350. default  settings.   Generic ccoonnffiigguurree options are discussed
  351. in  _d_o_c_s_/_I_N_S_T_A_L_L.   Options  that  are   specific   to   the
  352. man_db-2.3.x package are described below.
  353.  
  354. --enable-debug
  355.      By  default,  the configuration process creates produc-
  356.      tion quality Makefiles.  This option,  which  takes  no
  357.      argument,  changes  certain  values to aid in debugging
  358.      man_db-2.3.x. It does not alter the physical  behaviour
  359.      of any of the programs.
  360.  
  361. --enable-setuid[=ARG]
  362.      By  default,  mmaann will be installed as a setuid program
  363.      to user man. Use this option with an argument to change
  364.      the setuid owner.
  365.  
  366. --disable-setuid
  367.      Use  this option to install mmaann as a non-setuid program
  368.      and to change  the  default  cat  and  database  files'
  369.      access flags to allow users to modify them.
  370.  
  371. --with-device=DEVICE
  372.      Use  this  flag to alter the default output device used
  373.      by NNRROOFFFF. DEVICE is passed to NNRROOFFFF with the -T option.
  374.      ccoonnffiigguurree  will  test that NNRROOFFFF will run with the sup-
  375.      plied device argument.
  376.  
  377. --with-db=LIBRARY
  378.      configure will look for database interface libraries in
  379.      the  order  Berkeley DB, gdbm and finally ndbm and will
  380.      #define appropriate variables relative to the first one
  381.      found. To override the built in order on platforms hav-
  382.      ing a choice of interface library, use this  option  to
  383.      specify which library to use.
  384.  
  385.  
  386.  
  387. ____________________
  388.    4 Written and maintained by James Clark <jjc@jclark.com>
  389.  
  390.  
  391.  
  392.  
  393.                               44
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401. mmaann__ddbb--22..33..xx             mmaannuuaall vv00..55          AApprriill 1188,, 11999955
  402.  
  403.  
  404. 22..  TThhee ssppeecciiffiiccss ooff SSeeccttiioonnss
  405.  
  406. 22..11..  PPaacckkaaggee ssppeecciiffiicc mmaannuuaall ppaaggee sseeccttiioonnss
  407.  
  408. The use of package specific manual page sections is discour-
  409. aged as packages large enough to warrant their  own  section
  410. probably  contain  manual pages that span other sections. An
  411. example might be package ffoooo that has it's own section
  412.  
  413.      _/_u_s_r_/_m_a_n_/_m_a_n_f_o_o
  414.  
  415. which contains manual pages describing  it's  programs,  the
  416. library  routines it offers and the format of several of its
  417. configuration files. These pages would normally be allocated
  418. to  sections 11, 33 and 55 respectively and thus combining them
  419. all under section ffoooo is misleading.  Subtle  problems  will
  420. arise if there are any base name-space clashes with standard
  421. manual pages, eg.  eexxiitt(3), eexxiitt(foo) and the order in which
  422. they should be shown.
  423.  
  424. There are two standard solutions to this problem.
  425.  
  426.  (1)   Create a separate manual page hierarchy for the pack-
  427.        age's manual pages such as
  428.  
  429.            _/_u_s_r_/_l_o_c_a_l_/_p_a_c_k_a_g_e_s_/_f_o_o_/_m_a_n
  430.  
  431.  
  432.  (2)   Install the pages in their relevant sections, with  a
  433.        unique extension appended to the filename such that
  434.  
  435.            _/_u_s_r_/_m_a_n_/_m_a_n_f_o_o_/_e_x_i_t_._f_o_o
  436.  
  437.        would instead be installed as
  438.  
  439.            _/_u_s_r_/_m_a_n_/_m_a_n_1_/_e_x_i_t_._1_f_o_o
  440.  
  441.  
  442. Only  (2) offers a complete solution to manual page ordering
  443. problems  and  allows  users  to  access  the  desired  page
  444. directly.
  445.  
  446. 22..22..  SSeelleeccttiinngg aa sseeccttiioonn ttyyppee
  447.  
  448. 22..22..11..  SSppeecciiffyyiinngg aa sseeccttiioonn
  449.  
  450. This is done via use of the section argument to man
  451.      ____________
  452.      |_m_a_n__1__e_x_i_t_|_
  453.  
  454. will  look for _e_x_i_t_._1_* in section 11 of the manual. If _e_x_i_t_._1
  455. exists, it will be displayed in preference to _e_x_i_t_._1_f_o_o
  456.  
  457.  
  458.  
  459.                               55
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467. mmaann__ddbb--22..33..xx             mmaannuuaall vv00..55          AApprriill 1188,, 11999955
  468.  
  469.      _______________
  470.      |_m_a_n__1_f_o_o__e_x_i_t_|_
  471.  
  472. will look for _e_x_i_t_._1_f_o_o_* in section 11  of  the  manual.  The
  473. asterisk  (*)  represents a wild-card of any type or length,
  474. including length zero.
  475.  
  476. For an argument to be interpreted as a section  name  rather
  477. than  a  page name, it must either begin with a digit, or be
  478. included in the standard section list.  The default  section
  479. list  is defined in _i_n_c_l_u_d_e_/_m_a_n_c_o_n_f_i_g_._h to be 11, nn, ll, 88, 33,
  480. 22, 55, 44, 99, 66 and 77.  This should be modified in  order  and
  481. content to meet the local conventions.
  482.  
  483. Every subdirectory section name in the entire system must be
  484. in the list, including sections  found  in  imported  manual
  485. page  hierarchies.  The order is important because in normal
  486. operation, mmaann will only display the first  manual  page  it
  487. finds  that meets the search criteria. Using the ----aallll argu-
  488. ment will cause mmaann to attempt to display all  manual  pages
  489. that  meet the criteria. See mmaann(1) for further information.
  490.  
  491. Having an excess of sections listed will not slow mmaann  down.
  492.  
  493. 22..22..22..  SSppeecciiffyyiinngg aann eexxtteennssiioonn
  494.  
  495. If  the section is unknown, but the package extension is, it
  496. is possible to use the extension argument
  497.      _________________
  498.      |_m_a_n__-_e__f_o_o__e_x_i_t_|_
  499.  
  500. to search in all sections for manual pages named  _e_x_i_t  from
  501. package _f_o_o.
  502.  
  503.  
  504.  
  505.  
  506.  
  507.  
  508.  
  509.  
  510.  
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525.                               66
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533. mmaann__ddbb--22..33..xx             mmaannuuaall vv00..55          AApprriill 1188,, 11999955
  534.  
  535.  
  536. 33..  FFiilleessyysstteemm ssttrruuccttuurree
  537.  
  538. 33..11..  MMaannuuaall ppaaggee hhiieerraarrcchhiieess
  539.  
  540. It is often common for manual page systems to have more than
  541. one manual page hierarchy. Indeed one of the systems  I  use
  542. has the following globally accessible hierarchies
  543.  
  544.      _/_u_s_r_/_m_a_n
  545.      _/_u_s_r_/_l_o_c_a_l_/_m_a_n
  546.      _/_u_s_r_/_l_o_c_a_l_/_t_e_x_/_m_a_n
  547.      _/_u_s_r_/_l_o_c_a_l_/_p_b_m_/_m_a_n
  548.      _/_u_s_r_/_X_1_1_R_6_/_m_a_n
  549.      _/_u_s_r_/_o_p_e_n_w_i_n_/_m_a_n
  550.      _/_u_s_r_/_l_o_c_a_l_/_p_a_c_k_a_g_e_s_/_p_v_m_/_m_a_n
  551.  
  552. A  full  system  $MMAANNPPAATTHH would be a colon separated list of
  553. these directories The order is important, and is observed by
  554. man_db's  search algorithms.  The order is very much related
  555. to the users $PPAATTHH environment variable, and should  be  set
  556. on  a  per  user basis, or not set at all. If a user's $PPAATTHH
  557. causes
  558.  
  559.      _/_u_s_r_/_l_o_c_a_l_/_p_a_c_k_a_g_e_s_/_b_i_n_/_f_o_o_b_a_r
  560.  
  561. to be executed in preference to
  562.  
  563.      _/_u_s_r_/_b_i_n_/_f_o_o_b_a_r,
  564.  
  565. it is essential that
  566.      ____________
  567.      |_m_a_n__f_o_o_b_a_r_|_
  568.  
  569. displays the manual page located within
  570.  
  571.      _/_u_s_r_/_l_o_c_a_l_/_p_a_c_k_a_g_e_s_/_m_a_n
  572.  
  573. rather than within
  574.  
  575.      _/_u_s_r_/_m_a_n
  576.  
  577. To ensure correct order, the program mmaannppaatthh may be used  to
  578. set  the  $MMAANNPPAATTHH  environment variable. See mmaannppaatthh(1) and
  579. mmaannppaatthh(5) for details.
  580.  
  581. 33..22..  SSeettttiinngg tthhee MMAANNPPAATTHH
  582.  
  583. If using a Bourne style login shell such as  bbaasshh,  kksshh,  or
  584. zzsshh, the commands
  585.  
  586.      export MANPATH
  587.      MANPATH=`manpath -q`
  588.  
  589.  
  590.  
  591.                               77
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599. mmaann__ddbb--22..33..xx             mmaannuuaall vv00..55          AApprriill 1188,, 11999955
  600.  
  601.  
  602. can be added to $$HHOOMMEE_/_._p_r_o_f_i_l_e
  603.  
  604. If using a C style login shell such as ccsshh or ttccsshh, the com-
  605. mands
  606.  
  607.      setenv MANPATH `manpath -q`
  608.  
  609. can be added to $$HHOOMMEE_/_._l_o_g_i_n
  610.  
  611. N.B.  $PPAATTHH must be set prior to using mmaannppaatthh.  The setting
  612. of  $MMAANNPPAATTHH  is  actually  unnecessary  as the man_db-2.3.x
  613. utilities will dynamically determine the manpath if $MMAANNPPAATTHH
  614. is unset.
  615.  
  616. 33..33..  OOtthheerr OOSS''ss mmaannuuaall ppaaggeess
  617.  
  618. It  is  common to have collections of heterogeneous computer
  619. systems linked together in a network. In some circumstances5
  620. it  is advantageous to be able to access the manual pages of
  621. these other systems directly from your system.  This feature
  622. is  known  as  alternate system support. The accepted way to
  623. setup this support is to NFS mount the  respective  systems'
  624. manual page hierarchies under the native manual page hierar-
  625. chies. An example:
  626.  
  627.  
  628.              +--------+-----------------------+
  629.              |System  | Manual page hierarchy |
  630.              +--------+-----------------------+
  631.              |<local> | /usr/man              |
  632.              |newOS   | /usr/man/newOS        |
  633.              |userix  | /usr/man/userix       |
  634.              |<local> | /usr/local/man        |
  635.              |newOS   | /usr/local/man/newOS  |
  636.              |userix  | /usr/local/man/userix |
  637.              +--------+-----------------------+
  638.  
  639. Rather than have multiple NFS mounts from a single  machine,
  640. this may be accomplished by NFS mounting
  641.  
  642.      _<_o_t_h_e_r_-_s_y_s_>_:_/_u_s_r
  643.  
  644. somewhere  on  the  local  system  and  using symbolic links
  645. within the manual hierarchies.  To  access  these  _a_l_t_e_r_n_a_t_e
  646. _s_y_s_t_e_m_s using mmaann use the --mm option, eg.
  647.      __________________________________________
  648.      |_m_a_n__-_-_a_l_l__-_-_s_y_s_t_e_m__u_s_e_r_i_x_:_n_e_w_O_S__5__p_a_s_s_w_d_|_
  649.  
  650.  
  651. ____________________
  652.    5 writing portable software instantly comes to mind
  653.  
  654.  
  655.  
  656.  
  657.                               88
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664.  
  665. mmaann__ddbb--22..33..xx             mmaannuuaall vv00..55          AApprriill 1188,, 11999955
  666.  
  667.  
  668. would   provide   manual  pages  showing  the  structure  of
  669. _/_e_t_c_/_p_a_s_s_w_d on systems uusseerriixx and nneewwOOSS in  that  order.   A
  670. manual  page  would _n_o_t be displayed about the local systems
  671. conventions.  Please read the relevant man_db utility's man-
  672. ual page for further and more specific information.
  673.  
  674. 33..44..  NNLLSS mmaannuuaall ppaaggeess
  675.  
  676. NLS  manual  pages  should be put in NLS subdirectories of a
  677. standard manual page hierarchy.  A  table  illustrating  the
  678. concept is reproduced from the "Linux Filesystem Structure"6
  679. (FFSSSSTTNNDD)  manual  from  which  further  information  may  be
  680. obtained.
  681.  
  682.  
  683. +---------+----------------+-----------------+----------------------+
  684. |Language | Territory      | Character Set   | Directory            |
  685. +---------+----------------+-----------------+----------------------+
  686. |English  | --             | ASCII           | /usr/man/en          |
  687. |English  | United Kingdom | ASCII           | /usr/man/en_GB       |
  688. |English  | United States  | ASCII           | /usr/man/en_US       |
  689. |French   | Canada         | ISO 8859-1      | /usr/man/fr_CA       |
  690. |French   | France         | ISO 8859-1      | /usr/man/fr_FR       |
  691. |German   | Germany        | ISO 646         | /usr/man/de_DE.646   |
  692. |German   | Germany        | ISO 6937        | /usr/man/de_DE.6937  |
  693. |German   | Germany        | ISO 8859-1      | /usr/man/de_DE.88591 |
  694. |German   | Switzerland    | ISO 646         | /usr/man/de_CH.646   |
  695. |Japanese | Japan          | JIS             | /usr/man/ja_JP.jis   |
  696. |Japanese | Japan          | SJIS            | /usr/man/ja_JP.sjis  |
  697. |Japanese | Japan          | UJIS (or EUC-J) | /usr/man/ja_JP.ujis  |
  698. +---------+----------------+-----------------+----------------------+
  699.  
  700. Each of these directories are  then  interpreted  as  manual
  701. page  hierarchies  themselves and may contain the usual sec-
  702. tion subdirectories.  Access to NLS manual pages is achieved
  703. via  use  of  the  sseettllooccaallee(3)  function which queries user
  704. environment  variables  to  determine  the  current  locale.
  705. Internally  to  the  man_db utilities, this locale string is
  706. appended to each manpath element and the resultant NLS  man-
  707. path  element  is  searched before the standard manpath ele-
  708. ment. In this way, an  NLS  manual  page  that  matches  the
  709. search  criteria  will  be  shown  before or in place of the
  710. standard American English page.
  711.  
  712. If a user's $MMAANNPPAATTHH consists of or is determined as
  713.  
  714.      _/_u_s_r_/_l_o_c_a_l_/_m_a_n_:_/_u_s_r_/_m_a_n_:_/_u_s_r_/_X_1_1_R_6_/_m_a_n
  715.  
  716. ____________________
  717.    6  written  and  maintained  by  Daniel  Quinlan   <quin-
  718. lan@yggdrasil.com>
  719.  
  720.  
  721.  
  722.  
  723.                               99
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730.  
  731. mmaann__ddbb--22..33..xx             mmaannuuaall vv00..55          AApprriill 1188,, 11999955
  732.  
  733.  
  734. and their locale is set to ddee__DDEE, the command
  735.      ________________________________
  736.      |_m_a_n__-_-_s_y_s_t_e_m__u_s_e_r_i_x_:_m_a_n__f_o_o_b_a_r_|_
  737.  
  738. would produce the following internal man_db manpath elements
  739.  
  740.      _/_u_s_r_/_l_o_c_a_l_/_m_a_n_/_u_s_e_r_i_x_/_d_e___D_E
  741.      _/_u_s_r_/_l_o_c_a_l_/_m_a_n_/_u_s_e_r_i_x
  742.      _/_u_s_r_/_m_a_n_/_u_s_e_r_i_x_/_d_e___D_E
  743.      _/_u_s_r_/_m_a_n_/_u_s_e_r_i_x
  744.      _/_u_s_r_/_X_1_1_R_6_/_m_a_n_/_u_s_e_r_i_x_/_d_e___D_E
  745.      _/_u_s_r_/_X_1_1_R_6_/_m_a_n_/_u_s_e_r_i_x
  746.      _/_u_s_r_/_l_o_c_a_l_/_m_a_n_/_d_e___D_E
  747.      _/_u_s_r_/_l_o_c_a_l_/_m_a_n
  748.      _/_u_s_r_/_m_a_n_/_d_e___D_E
  749.      _/_u_s_r_/_m_a_n_/_m_a_n
  750.      _/_u_s_r_/_X_1_1_R_6_/_m_a_n_/_d_e___D_E
  751.      _/_u_s_r_/_X_1_1_R_6_/_m_a_n
  752.  
  753. ffoooobbaarr  would  be  searched  for in the order of manual page
  754. hierarchies listed.
  755.  
  756. 33..44..11..  IISSOO 88885599--11 ((llaattiinn11)) mmaannuuaall ppaaggeess
  757.  
  758. By default NNRROOFFFF will format manual pages into a form  suit-
  759. able  for a typewriter style device, e.g. a terminal screen.
  760. GGNNUU  NNRROOFFFF  is capable7 of formatting ROFF into a form suit-
  761. able for 8-bit latin1 capable output devices. To enable out-
  762. put for such a device, give the option
  763.  
  764. --with-device=DEVICE
  765.  
  766. to ccoonnffiigguurree where DEVICE is the suitable and supported out-
  767. put format, in this case llaattiinn11.
  768.  
  769. 33..44..22..  DDiissppllaayyiinngg llaattiinn11  cchhaarraacctteerrss  oonn  aa  LLiinnuuxx  vviirrttuuaall
  770. tteerrmmiinnaall
  771.  
  772. To  enable  console  based viewing of latin1 characters on a
  773. Linux system, you must have the kbd8 package installed.  The
  774. following  commands  included  within an initialisation file
  775. such as _/_e_t_c_/_r_c_._d_/_r_c_._l_o_c_a_l will enable the display of latin1
  776. fonts on the first 5 virtual terminals.
  777.  
  778. ---< part of /etc/rc.d/rc.local >---
  779. ____________________
  780.    7 see nnrrooffff(5) for the output  device  formats  available
  781. with your NNRROOFFFF
  782.    8 written and maintained by Andries Brouwer <aeb@cwi.nl>.
  783. Version  0.90  and above does not require the use of mmaappssccrrnn
  784. as illustrated in the script.
  785.  
  786.  
  787.  
  788.  
  789.                              1100
  790.  
  791.  
  792.  
  793.  
  794.  
  795.  
  796.  
  797. mmaann__ddbb--22..33..xx             mmaannuuaall vv00..55          AApprriill 1188,, 11999955
  798.  
  799.  
  800. # sort out the vt font
  801. if [ -x /bin/setfont ]; then
  802.         /bin/setfont /etc/kbd/consolefonts/lat1-16.psf
  803. fi
  804.  
  805. # load the keymap transformation to do when activating new font
  806. if [ -x /bin/mapscrn ]; then
  807.         /bin/mapscrn /etc/kbd/consoletrans/trivial
  808. fi
  809.  
  810. # enable new font
  811. for t in 1 2 3 4 5; do
  812.    echo -n -e "\033(K" > /dev/tty$t
  813. done
  814. ---< part of /etc/rc.d/rc.local >---
  815.  
  816. For  display  under  the "X Window System", a suitable 8 bit
  817. clean terminal emulator is required.
  818.  
  819. 33..44..33..  VViieewwiinngg AASSCCIIII  ppaaggeess  ffoorrmmaatttteedd  ffoorr  llaattiinn11  oouuttppuutt
  820. ddeevviiccee
  821.  
  822. When  formatting  an  ASCII  manual page for a latin1 output
  823. device, GGNNUU NNRROOFFFF will take advantage of the  extra  charac-
  824. ters  available and will always produce a text page contain-
  825. ing some latin1 (8-bit) symbols.  The  table9  below,  taken
  826. from mmaann(1) illustrates the differences.
  827.  
  828.  
  829.      +--------------------+-------+------------+-------+
  830.      |Description         | Octal | ISO 8859-1 | ASCII |
  831.      +--------------------+-------+------------+-------+
  832.      |continuation hyphen |  255  |     -      |   -   |
  833.      |bullet (middle dot) |  267  |     +o      |   o   |
  834.      |acute accent        |  264  |     '      |   '   |
  835.      |multiplication sign |  327  |     x      |   x   |
  836.      +--------------------+-------+------------+-------+
  837.  
  838. To display such symbols on a 7 bit terminal or terminal emu-
  839. lator, they must be translated back into standard ASCII. The
  840. --77  option with mmaann will enable this simple reverse transla-
  841. tion.
  842.  
  843. This option may be useful if your site has both 7 and  8-bit
  844. capable  output devices and nroff is using the latin1 output
  845. device to format manual pages.
  846.  
  847. ____________________
  848.    9 The ISO 8859-1 and ASCII columns of this table will  be
  849. identical  if  this  manual was formatted for an ASCII based
  850. typewriter display, i.e. using NNRROOFFFF in it's native mode.
  851.  
  852.  
  853.  
  854.  
  855.                              1111
  856.  
  857.  
  858.  
  859.  
  860.  
  861.  
  862.  
  863. mmaann__ddbb--22..33..xx             mmaannuuaall vv00..55          AApprriill 1188,, 11999955
  864.  
  865.  
  866. 33..55..  CCaatt ppaaggeess
  867.  
  868. It has become standard practice to store the formatted  man-
  869. ual pages on disk so that subsequent requests for the manual
  870. page do not have to involve the  formatting  process.  These
  871. pre-formatted  manual pages are known as _c_a_t pages. Although
  872. cat pages require additional disk storage requirements, they
  873. provide a substantial speed increase and their use is recom-
  874. mended.
  875.  
  876. The automatic support of storing  and  using  cat  pages  is
  877. brought  about  by  simply creating suitable directories for
  878. them.
  879.  
  880. 33..66..  CCaatt ppaaggee hhiieerraarrcchhiieess
  881.  
  882. Traditionally, cat pages were stored under the  same  manual
  883. hierarchy  as  their source manual pages, in _c_a_t_<_s_e_c_> subdi-
  884. rectories rather than _m_a_n_<_s_e_c_>.  This  situation  is  rather
  885. limiting in several situations
  886.  
  887.  +o When  it  is  advantageous  to  mount _/_u_s_r as a read-only
  888.    filesystem. Cat pages cannot be supported in this  situa-
  889.    tion without use of symbolic links to various other areas
  890.    of the filesystem. This situation is a greater problem if
  891.    the media itself is read-only, such as CD-ROM.
  892.  +o When NFS mounting alternate OS's manual page hierarchies.
  893.    The alternate system may be under someone else's  control
  894.    and  they  may not want cat pages stored on their system.
  895.    In fact it is usually a good idea to  export  the  manual
  896.    page  filesystems  read-only, or import them that way. It
  897.    is possible to avoid the problems, this  time  with  even
  898.    more symbolic links that may need periodic updating.
  899.  +o If  there  is  a  mixture  of  normal cat files and stray
  900.    cats10, it is very difficult to periodically _t_r_i_m the cat
  901.    space disk usage by removing seldom accessed cat files.
  902.  
  903. To avoid  all  of  these  problems  simultaneously,  it  was
  904. decided to support local cat page directory caches.
  905.  
  906. 33..77..  LLooccaall ccaatt ppaaggee ddiirreeccttoorryy ccaacchheess
  907.  
  908. Any  location for cat page hierarchy may be specified in the
  909. man_db configuration file.  The  location  of  the  database
  910. cache associated with each manual page hierarchy will always
  911. be at the root of the cat page hierarchy.  By  default,  the
  912. cat  page  hierarchy shadows the manual page hierarchy.  The
  913. FFSSSSTTNNDD  proposes  _/_v_a_r_/_c_a_t_m_a_n  as  the  location  for   such
  914. ____________________
  915.    10 cat files that have no source manual page,  i.e.  they
  916. cannot be recreated.
  917.  
  918.  
  919.  
  920.  
  921.                              1122
  922.  
  923.  
  924.  
  925.  
  926.  
  927.  
  928.  
  929. mmaann__ddbb--22..33..xx             mmaannuuaall vv00..55          AApprriill 1188,, 11999955
  930.  
  931.  
  932. directories although man_db-2.3.x allows any directory hier-
  933. archy to be used.  The FFSSSSTTNNDD path transformation rule is as
  934. follows
  935.  
  936.      _/_u_s_r_/_<_h_i_e_r_a_r_c_h_y_>_/_m_a_n_/_<_l_o_c_a_l_e_>_/_m_a_n_<_s_e_c_>_/_p_a_g_e_._<_s_e_c_>_<_e_x_t_>
  937.  
  938. should be formatted into the cat file
  939.  
  940.      _/_v_a_r_/_c_a_t_m_a_n_/_<_h_i_e_r_a_r_c_h_y_>_/_<_l_o_c_a_l_e_>_/_c_a_t_<_s_e_c_>_/_p_a_g_e_._<_s_e_c_>_<_e_x_t_>
  941.  
  942. where the _<_l_o_c_a_l_e_> directory component may  be  missing  and
  943. _<_e_x_t_> may be an empty string.
  944.  
  945. The  suggestion is that stray cats are located in the tradi-
  946. tional hierarchy under _/_u_s_r whereas re-creatable  cat  pages
  947. are  stored  under the local writable hierarchy _/_v_a_r_/_c_a_t_m_a_n_.
  948. mmaann follows strict rules in determining which file  is  dis-
  949. played.
  950.  
  951. As  an  example,  the  following route is taken if all three
  952. files exist.
  953.  
  954.  (1)   Check relative time stamps of the manual file and the
  955.        traditional  cat file.  If the cat file is up to date
  956.        (has a more recent time stamp), display it.
  957.  
  958.  (2)   The traditional cat file is out of date. Check  rela-
  959.        tive time stamps of the manual file and the alternate
  960.        cat file. If the cat file is up to date, display  it.
  961.  
  962.  (3)   The  alternate  cat  file  is out of date. Format the
  963.        manual file and display the result in the foreground,
  964.        while  updating  the  alternate cat file in the back-
  965.        ground.
  966.  
  967.  
  968.  
  969.  
  970.  
  971.  
  972.  
  973.  
  974.  
  975.  
  976.  
  977.  
  978.  
  979.  
  980.  
  981.  
  982.  
  983.  
  984.  
  985.  
  986.  
  987.                              1133
  988.  
  989.  
  990.  
  991.  
  992.  
  993.  
  994.  
  995. mmaann__ddbb--22..33..xx             mmaannuuaall vv00..55          AApprriill 1188,, 11999955
  996.  
  997.  
  998. 44..  CCoommpprreessssiioonn
  999.  
  1000. 44..11..  CCoommpprreesssseedd mmaannuuaall ppaaggeess
  1001.  
  1002. It is possible to maintain a  system  of  compressed  manual
  1003. pages.   The use of this feature is not recommended for sys-
  1004. tems that have adequate disk space  to  store  their  manual
  1005. pages uncompressed. Subsequent decompression of these manual
  1006. pages will cause several bottlenecks in the formatting  pro-
  1007. cess.
  1008.  
  1009. Presently, the compression extension/decompressor pairs must
  1010. be known at compile time although any number may be  defined
  1011. and   used.   The   following  structure  is  predefined  in
  1012. man_db-2.3.x
  1013.  
  1014.  
  1015.                  +----------+--------------+
  1016.                  |Extension | Decompressor |
  1017.                  +----------+--------------+
  1018.                  |gz        | gzip -dc     |
  1019.                  |z         | gzip -dc     |
  1020.                  |Z         | compress -dc |
  1021.                  +----------+--------------+
  1022.  
  1023. It is a relatively easy operation to include  further  pairs
  1024. in this structure. See _i_n_c_l_u_d_e_/_c_o_m_p___s_r_c_._h for details and an
  1025. example.
  1026.  
  1027. Support for compressed manual pages  is  compiled  into  the
  1028. man_db-2.3.x  utilities  by  default.  To completely disable
  1029. this support, edit _i_n_c_l_u_d_e_/_c_o_n_f_i_g_._h and comment out the fol-
  1030. lowing line
  1031.  
  1032. #define COMP_SRC 1
  1033.  
  1034. This  will enable a minor speed increase, but note that sup-
  1035. port for stray cats with  any  compression  extension  other
  1036. than the default will also be disabled.
  1037.  
  1038. 44..22..  CCoommpprreesssseedd ccaatt ppaaggeess
  1039.  
  1040. man_db-2.3.x compresses cat files by default. During config-
  1041. uration, ccoonnffiigguurree will try to find ggzziipp and if so, all  cat
  1042. files produced by mmaann will be compressed with
  1043.  
  1044.      ggzziipp --77cc
  1045.  
  1046. and have a ..ggzz extension appended.  If ggzziipp is not found,
  1047.  
  1048.      ccoommpprreessss --cc
  1049.  
  1050.  
  1051.  
  1052.  
  1053.                              1144
  1054.  
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060.  
  1061. mmaann__ddbb--22..33..xx             mmaannuuaall vv00..55          AApprriill 1188,, 11999955
  1062.  
  1063.  
  1064. is  used as the compressor and the extension ..ZZ is appended.
  1065.  
  1066. To store cat files in an uncompressed state and  to  disable
  1067. compressed    extension    processing    completely,    edit
  1068. _i_n_c_l_u_d_e_/_c_o_n_f_i_g_._h and comment out the following line
  1069.  
  1070. #define COMP_CAT 1
  1071.  
  1072. 44..22..11..  SSttrraayy ccaattss
  1073.  
  1074. Normally, mmaann will only look for cat files with the  default
  1075. compression  extension. The default compression extension is
  1076. dependent on the default compressor  and  may  be  an  empty
  1077. string if the support for compressed cats is disabled.
  1078.  
  1079. It  is  possible  for a system to be supplied with stray cat
  1080. files located in the traditional cat page hierarchy. To make
  1081. matters  worse,  they  may have compression extensions other
  1082. than the default and reside on  read-only  media.   In  such
  1083. circumstances,  stray  cat  files  will be accepted with any
  1084. compression extension that  is  also  supported  for  manual
  1085. pages.
  1086.  
  1087. This special treatment of stray cat pages is removed if sup-
  1088. port for compressed manual pages is turned off or not avail-
  1089. able.
  1090.  
  1091.  
  1092.  
  1093.  
  1094.  
  1095.  
  1096.  
  1097.  
  1098.  
  1099.  
  1100.  
  1101.  
  1102.  
  1103.  
  1104.  
  1105.  
  1106.  
  1107.  
  1108.  
  1109.  
  1110.  
  1111.  
  1112.  
  1113.  
  1114.  
  1115.  
  1116.  
  1117.  
  1118.  
  1119.                              1155
  1120.  
  1121.  
  1122.  
  1123.  
  1124.  
  1125.  
  1126.  
  1127. mmaann__ddbb--22..33..xx             mmaannuuaall vv00..55          AApprriill 1188,, 11999955
  1128.  
  1129.  
  1130. 55..  FFoorrmmaattttiinngg
  1131.  
  1132. As  already  pointed  out in the introduction, there are two
  1133. primary formatters common to UUNNIIXX: NNRROOFFFF and TTRROOFFFF.
  1134.  
  1135. In the following sections, I will  use  the  term  TTRROOFFFF  to
  1136. describe  the typesetter formatter and NNRROOFFFF to describe the
  1137. typewriter formatter. The term ROFF will be used to describe
  1138. a generic formatter.
  1139.  
  1140. 55..11..  GGRROOFFFF
  1141.  
  1142. If using the GGRROOFFFF package, there is a further choice, GGRROOFFFF
  1143. itself.  Essentially, GGRROOFFFF forms a pipeline  of  processors
  1144. including TTRROOFFFF and an output processor which translates the
  1145. ditroff produced by TTRROOFFFF into the appropriate  output  for-
  1146. mat.  The  default  output  format,  or device, for GGRROOFFFF is
  1147. PostScript.  Anything  else  must  be  specified  using  the
  1148. device argument.  To illustrate GGRROOFFFF, the command
  1149.      _______________________
  1150.      |_g_r_o_f_f__-_T_d_v_i__/_d_e_v_/_n_u_l_l_|_
  1151.  
  1152. will form the following pipeline
  1153.  
  1154.      troff -Tdvi /dev/null | grodvi
  1155.  
  1156. If  GGRROOFFFF  is  tied to mmaann''ss --TT option, it is still possible
  1157. for mmaann to produce ditroff via use of the --ZZ option.
  1158.  
  1159. In GGRROOFFFF 1.09, NNRROOFFFF is bundled as a shell script that calls
  1160. GGRROOFFFF,  which  in  turn calls TTRROOFFFF with the default options
  1161. --WWaallll --mmttttyy--cchhaarr --TTaasscciiii, passing the result through  ggrroottttyy
  1162. before it finally reaches the screen.
  1163.  
  1164. It  is  imperative  that  the  script  does  not  pass  pre-
  1165. processing options to GGRROOFFFF command line as mmaann  takes  care
  1166. of  this separately. The file _t_o_o_l_s_/_n_r_o_f_f___s_c_r_i_p_t may be used
  1167. as a basis for an NNRROOFFFF script if  your  system  is  without
  1168. one.
  1169.  
  1170. 55..22..  DDeevviicceess
  1171.  
  1172. Both  NNRROOFFFF  and GGRROOFFFF may allow output device selection. As
  1173. mentioned previously, classic NNRROOFFFF produces output suitable
  1174. for a typewriter device, classic TTRROOFFFF produces output suit-
  1175. able for a CC//AA//TT and GGRROOFFFF produces output  suitable  for  a
  1176. PostScript interpreting device.
  1177.  
  1178. 55..33..  MMaaccrrooss
  1179.  
  1180. There are several ROFF macros in existence that are suitable
  1181. for manual pages.  Unfortunately, they tend to be incompati-
  1182. ble with each other.
  1183.  
  1184.  
  1185.                              1166
  1186.  
  1187.  
  1188.  
  1189.  
  1190.  
  1191.  
  1192.  
  1193. mmaann__ddbb--22..33..xx             mmaannuuaall vv00..55          AApprriill 1188,, 11999955
  1194.  
  1195.  
  1196. During  configuration, ccoonnffiigguurree will attempt to determine a
  1197. suitable macro for the local system's  manual  page  collec-
  1198. tion.  It  attempts  to  use  NNRROOFFFF with the following three
  1199. macro packages:
  1200.  
  1201.  
  1202.       +--------------+----------------+---------------+
  1203.       |macro package | macro filename | nroff command |
  1204.       +--------------+----------------+---------------+
  1205.       |andoc         | tmac.andoc     | nroff -mandoc |
  1206.       |an            | tmac.an        | nroff -man    |
  1207.       |doc           | tmac.doc       | nroff -mdoc   |
  1208.       +--------------+----------------+---------------+
  1209.  
  1210. The first that succeeds is used. Macro aannddoocc is suitable for
  1211. manual  pages written using either aann or ddoocc macro commands,
  1212. but not both.
  1213.  
  1214. 55..44..  PPrree--ffoorrmmaatt pprroocceessssoorrss ((pprree--pprroocceessssoorrss))
  1215.  
  1216. Manual pages may require pre-processing by any of  the  fol-
  1217. lowing
  1218.  
  1219.  
  1220.              +--------+----+------------------+
  1221.              |Program | ID | Pre-processes    |
  1222.              +--------+----+------------------+
  1223.              |eqn     | e  | equations        |
  1224.              |tbl     | t  | tables           |
  1225.              |grap    | g  | graphs           |
  1226.              |pic     | p  | pictures         |
  1227.              |refer   | r  | A bibliography   |
  1228.              |vgrind  | v  | program listings |
  1229.              +--------+----+------------------+
  1230.  
  1231. It  is  possible to assign a default pre-processor list that
  1232. all manual pages will be passed through prior to the primary
  1233. formatter.  By  default,  this is empty. To define a default
  1234. list, edit _i_n_c_l_u_d_e_/_m_a_n_c_o_n_f_i_g_._h and un-comment the  following
  1235. line
  1236.  
  1237. /* #define DEFAULT_MANROFFSEQ   "t" */
  1238.  
  1239. which  will  enable ttbbll processing by default. To change the
  1240. list, replace the tt with  a  suitable  string  of  processor
  1241. ID's.
  1242.  
  1243. Pre-process  options  may be provided at run time in various
  1244. forms, but in general the pre-processors  required  by  each
  1245. manual  page  is  indicated  in the first line of the manual
  1246. page itself. See mmaann(1) for details.
  1247.  
  1248.  
  1249.  
  1250.  
  1251.                              1177
  1252.  
  1253.  
  1254.  
  1255.  
  1256.  
  1257.  
  1258.  
  1259. mmaann__ddbb--22..33..xx             mmaannuuaall vv00..55          AApprriill 1188,, 11999955
  1260.  
  1261.  
  1262. 55..55..  FFoorrmmaatt ssccrriippttss
  1263.  
  1264. It is very likely that alternate systems  manual  pages  may
  1265. require non-standard macro packages or possibly even special
  1266. pre-processors.  To tackle  such  problems,  special  format
  1267. scripts may be created on a per manual hierarchy basis.
  1268.  
  1269. If the file
  1270.  
  1271.      _<_m_a_n_u_a_l___h_i_e_r_a_r_c_h_y_>_/_m_a_n_d_b___n_f_m_t
  1272.  
  1273. exists  and is executable, it is expected to be able to cor-
  1274. rectly  format  a  manual  page   originating   from   _<_m_a_n_-
  1275. _u_a_l___h_i_e_r_a_r_c_h_y_>  to  its standard output. It will be supplied
  1276. with either two or three arguments:
  1277.  
  1278.     +o manual page filename
  1279.     +o pre-processor string
  1280.     +o ouput device (optional)
  1281.  
  1282. Similarly, if the option --TT_<_d_e_v_i_c_e_> or --tt  was  supplied  to
  1283. mmaann and the file
  1284.  
  1285.      _<_m_a_n_u_a_l___h_i_e_r_a_r_c_h_y_>_/_m_a_n_d_b___t_f_m_t
  1286.  
  1287. exists and is executable, it will be used in the same way.
  1288.  
  1289. An  example  of such a script, supplied by Markus Armbruster
  1290. <armbru@pond.sub.org>, who  provided  support  for  external
  1291. formatter scripts, can be found as _t_o_o_l_s_/_m_a_n_d_b___[_n_t_]_f_m_t
  1292.  
  1293. The  script can be used as both a NNRROOFFFF and TTRROOFFFF/GGRROOFFFF for-
  1294. mat script and can  be  installed  as  _m_a_n_d_b___n_f_m_t  and  hard
  1295. linked to _m_a_n_d_b___t_f_m_t after modification appropriate for your
  1296. particular site.
  1297.  
  1298.  
  1299.  
  1300.  
  1301.  
  1302.  
  1303.  
  1304.  
  1305.  
  1306.  
  1307.  
  1308.  
  1309.  
  1310.  
  1311.  
  1312.  
  1313.  
  1314.  
  1315.  
  1316.  
  1317.                              1188
  1318.  
  1319.  
  1320.  
  1321.  
  1322.  
  1323.  
  1324.  
  1325. mmaann__ddbb--22..33..xx             mmaannuuaall vv00..55          AApprriill 1188,, 11999955
  1326.  
  1327.  
  1328. 66..  TThhee iinnddeexx ddaattaabbaassee ccaacchheess
  1329.  
  1330. As mentioned in the introduction, man_db-2.3.x uses database
  1331. lookups to search for manual page locations and information.
  1332. When performing a manual  page  lookup  or  a  basic  wwhhaattiiss
  1333. search, the databases are searched in
  1334.  
  1335.      _k_e_y _-_> _c_o_n_t_e_n_t
  1336.  
  1337. mode  and  are  as  fast as the underlying databases can be.
  1338. When performing aapprrooppooss  or  special  wwhhaattiiss  searches,  the
  1339. databases  are  searched in a linear way, which although far
  1340. more expensive than _k_e_y_e_d lookup, is no  worse  than  tradi-
  1341. tional text based file searching.
  1342.  
  1343. 66..11..  iinnddeexx ddaattaabbaassee llooccaattiioonn
  1344.  
  1345. The databases are always located at the root of the cat page
  1346. hierarchy, whether this is the same as the manual page hier-
  1347. archy  or  not.   As file locking mechanisms are employed to
  1348. ensure that concurrent processes do not  update  a  database
  1349. simultaneously,  it  is almost imperative that the databases
  1350. reside on a local filesystem since file locking  across  NFS
  1351. filesystems may be unavailable or flaky. To avoid such prob-
  1352. lems, mmaann can be compiled without database maintenance  sup-
  1353. port.   See  the  section  titled  "Modes  of operation" for
  1354. details.
  1355.  
  1356. 66..11..11..  MMaannuuaall hhiieerraarrcchhiieess wwiitthh nnoo iinnddeexx ddaattaabbaassee
  1357.  
  1358. It is possible for the  man_db-2.3.x  utilities  to  operate
  1359. without  aid  from  an  index  database.  Under such circum-
  1360. stances, search methods will resort  to  file  globbing  and
  1361. whatis type searches are performed on any traditional whatis
  1362. text databases that may exist.   Only  the  traditional  cat
  1363. hierarchy is searched for cat files.
  1364.  
  1365. 66..11..22..  UUsseerr mmaannuuaall ppaaggee hhiieerraarrcchhiieess
  1366.  
  1367. A  user  may have any number of personal manual page hierar-
  1368. chies listed in their $MMAANNPPAATTHH.  By default, mmaann will  main-
  1369. tain mmaannddbb created databases at the root of user manual page
  1370. hierarchies.  The definition of a user manual  hierarchy  is
  1371. that  it  does not have an entry in the man_db configuration
  1372. file. See mmaannppaatthh(5) for details.
  1373.  
  1374. 66..22..  CCoonntteennttss ooff aann iinnddeexx ddaattaabbaassee
  1375.  
  1376. There are four kinds of entry in an index database.
  1377.  
  1378.  (1)   A direct entry regarding a  particular  manual  page.
  1379.        Manual  pages  that  are  unique in terms of name use
  1380.        just a single entry in the database and can be looked
  1381.  
  1382.  
  1383.                              1199
  1384.  
  1385.  
  1386.  
  1387.  
  1388.  
  1389.  
  1390.  
  1391. mmaann__ddbb--22..33..xx             mmaannuuaall vv00..55          AApprriill 1188,, 11999955
  1392.  
  1393.  
  1394.        up by simply using the name as the key.
  1395.  
  1396.  (2)   A  common  name index entry that lists the extensions
  1397.        of all of the manual pages sharing the  common  index
  1398.        entry  name.   Manual  pages that share common names,
  1399.        but have differing  extensions  each  have  a  single
  1400.        database entry, but this time they are looked up with
  1401.        a key comprised of their name  and  their  extension.
  1402.        The entire set of common named pages also has an com-
  1403.        mon name index entry that informs of  the  extensions
  1404.        available.
  1405.  
  1406.  (3)   An  indirect  entry  that  has  a pointer to the real
  1407.        entry. Manual pages that are whatis references  to  a
  1408.        particular  page do not physically exist so they have
  1409.        a pointer to the entry containing the location of the
  1410.        real manual page.
  1411.  
  1412.  (4)   Special identification entries. There are two special
  1413.        key  names,  "$mtime$"  that  references  an  integer
  1414.        describing the last modification time of the database
  1415.        and "$version$" that identifies the database  storage
  1416.        scheme version.
  1417.  
  1418. In  the following entries, the character "|" will be used to
  1419. separate the fields. In reality a tab is used.   Direct  and
  1420. indirect entries takes the form:
  1421.  
  1422.      _<_n_a_m_e_>                                               _-_>
  1423.      _<_e_x_t_>_|_<_s_e_c_>_|_<_m_t_i_m_e_>_|_<_I_D_>_|_<_r_e_f_>_|_<_c_o_m_p_>_|_<_w_h_a_t_i_s_>
  1424.  
  1425. Common name index entries take the form:
  1426.  
  1427.      _<_n_a_m_e_> _-_> _|_<_e_x_t_1_>_|_<_e_x_t_2_>_|_<_e_x_t_3_>_| _._._. _<_e_x_t_n_>
  1428.  
  1429. and common name direct or indirect entries take the form:
  1430.  
  1431.      _<_n_a_m_e_>_|_<_e_x_t_>                                         _-_>
  1432.      _<_e_x_t_>_|_<_s_e_c_>_|_<_m_t_i_m_e_>_|_<_I_D_>_|_<_r_e_f_>_|_<_c_o_m_p_>_|_<_w_h_a_t_i_s_>
  1433.  
  1434. where  in each case the filename being represented is formed
  1435. as
  1436.  
  1437.      _<_m_a_n_u_a_l___h_i_e_r_a_r_c_h_y_>_/_m_a_n_<_s_e_c_>_/_<_n_a_m_e_>_._<_e_x_t_>_._<_c_o_m_p_>
  1438.  
  1439. in the case of a manual page, or
  1440.  
  1441.      _<_c_a_t___h_i_e_r_a_r_c_h_y_>_/_c_a_t_<_s_e_c_>_/_<_n_a_m_e_>_._<_e_x_t_>_._<_c_o_m_p_>
  1442.  
  1443. in the case of a stray cat.
  1444.  
  1445. If any of the fields would be empty, a single "-" is  stored
  1446. in  its place.  _<_c_o_m_p_> represents the compression extension.
  1447.  
  1448.  
  1449.                              2200
  1450.  
  1451.  
  1452.  
  1453.  
  1454.  
  1455.  
  1456.  
  1457. mmaann__ddbb--22..33..xx             mmaannuuaall vv00..55          AApprriill 1188,, 11999955
  1458.  
  1459.  
  1460. _<_m_t_i_m_e_> is an integer  representing  the  last  modification
  1461. time  of the manual page, _<_r_e_f_> points to the entry contain-
  1462. ing the location of the real page and _<_I_D_>  is  one  of  the
  1463. following identification letters.
  1464.  
  1465.  
  1466. +---+------------+--------------------------------------------------------+
  1467. |ID | #define    | Description                                            |
  1468. +---+------------+--------------------------------------------------------+
  1469. |A  | ULT_MAN    | ultimate manual page, the full source nroff file       |
  1470. |B  | SO_MAN     | manual page containing a .so request to an ULT_MAN     |
  1471. |C  | WHATIS_MAN | virtual whatis referenced page pointing to an ULT_MAN  |
  1472. |D  | STRAY_CAT  | cat page with no source manual page                    |
  1473. |E  | WHATIS_CAT | virtual whatis referenced page pointing to a STRAY_CAT |
  1474. +---+------------+--------------------------------------------------------+
  1475.  
  1476. The _I_D illustrates the precedence. Some types of manual page
  1477. can be referenced by several means, e.g. .so  requested  and
  1478. whatis  referred. In such a case, only one reference must be
  1479. stored in the database, the precedence level decides  which.
  1480.  
  1481. 66..22..11..  FFaavvoouurriinngg ssttrraayy ccaattss
  1482.  
  1483. With  the  above  rules  of precedence, it is possible for a
  1484. valid stray cat page to be replaced  by  a  whatis  referred
  1485. page sharing identical name-space.
  1486.  
  1487. If  you would like to see the stray cat page kkiillll(1) instead
  1488. of the bbaasshh__bbuuiillttiinnss(1)  page  referenced  by  kkiillll(1)  edit
  1489. _l_i_b_d_b_/_d_b___s_t_o_r_a_g_e_._h and un-comment the following line
  1490.  
  1491. /* #define FAVOUR_STRAYCATS */
  1492.  
  1493. 66..22..22..  AAcccceessssddbb
  1494.  
  1495. A simple program, aacccceessssddbb is included with man_db-2.3.x. It
  1496. will output the data contained within a man_db database in a
  1497. human  readable form. By default, it will _d_u_m_p the data from
  1498. _/_v_a_r_/_c_a_t_m_a_n_/_i_n_d_e_x_._<_d_b_-_t_y_p_e_>, where _<_d_b_-_t_y_p_e_> is dependent on
  1499. the database library in use.
  1500.  
  1501. Supplying   an  argument  to  aacccceessssddbb  will  override  this
  1502. default.  Tabs are replaced in the output by a tilde "~"  in
  1503. the _k_e_y field and a single space in the _c_o_n_t_e_n_t field
  1504.  
  1505. aacccceessssddbb is not compiled by default. Type
  1506.      _______________
  1507.      |_m_a_k_e__a_c_c_e_s_s_d_b_|_
  1508.  
  1509. in the src directory to compile it.
  1510.  
  1511.  
  1512.  
  1513.  
  1514.  
  1515.                              2211
  1516.  
  1517.  
  1518.  
  1519.  
  1520.  
  1521.  
  1522.  
  1523. mmaann__ddbb--22..33..xx             mmaannuuaall vv00..55          AApprriill 1188,, 11999955
  1524.  
  1525.  
  1526. 66..22..33..  EExxaammppllee ddaattaabbaassee
  1527.  
  1528. As  an  example  of  both  aacccceessssddbb and the database storage
  1529. method, the output of
  1530.      ___________________________
  1531.      |_s_r_c_/_a_c_c_e_s_s_d_b__m_a_n_/_i_n_d_e_x_._b_t_|_
  1532.  
  1533. after first running
  1534.      _______________
  1535.      |_s_r_c_/_m_a_n_d_b__m_a_n_|_
  1536.  
  1537. from the top level build directory is included below.
  1538.  
  1539. $mtime$ -> "795987034"
  1540. $version$ -> "2.3.1"
  1541. apropos -> "1 1 795981542 A - - search the manual page names and descriptions"
  1542. catman -> "8 8 795981544 A - - create or update the pre-formatted manual pages"
  1543. man -> "1 1 795981542 A - - an interface to the on-line reference manuals"
  1544. mandb -> "8 8 795981544 A - - create or update the manual page index caches"
  1545. manpath -> " 1 5"
  1546. manpath~1 -> "1 1 795981542 A - - determine search path for manual pages"
  1547. manpath~5 -> "5 5 795981543 A - - format of the /etc/man_db.config file"
  1548. whatis -> "1 1 795981543 A - - search the manual page names"
  1549. zsoelim -> "1 1 795981543 A - - satisfy .so requests in roff input"
  1550.  
  1551. 66..33..  DDaattaabbaassee ttyyppeess
  1552.  
  1553. man_db-2.3.x has support  for  various  low  level  database
  1554. libraries  commonly  in  use  today.   The interfaces to the
  1555. libraries are known as
  1556.  
  1557.  +o ndbm (UUNNIIXX)
  1558.  +o gdbm (GGNNUU)
  1559.  +o btree (Berkeley DB)
  1560.  
  1561. man_db-2.3.x currently does not hold more than one  database
  1562. open at any time, so
  1563.  
  1564.  +o dbm (UUNNIIXX)
  1565.  
  1566. support could be added in the future.
  1567.  
  1568. 66..44..  lliimmiittaattiioonnss
  1569.  
  1570. The general differences and limitations are best compared in
  1571. a table.
  1572.  
  1573.  
  1574.  
  1575.  
  1576.  
  1577.  
  1578.  
  1579.  
  1580.  
  1581.                              2222
  1582.  
  1583.  
  1584.  
  1585.  
  1586.  
  1587.  
  1588.  
  1589. mmaann__ddbb--22..33..xx             mmaannuuaall vv00..55          AApprriill 1188,, 11999955
  1590.  
  1591.  
  1592. +------+-------------+----------+-----------------+--------------+-----------+
  1593. |      |             |   File   | Content memory  |  Concurrent  |           |
  1594. |Name  |    Type     |          +---------+-------+              | Shareable |
  1595. |      |             |   name   |  type   | limit |    access    |           |
  1596. +------+-------------+----------+---------+-------+--------------+-----------+
  1597. |ndbm  | hash        | index11  | static  | 1Kb   | none         | no        |
  1598. |gdbm  | hash        | index.db | dynamic | -     | file locking | no        |
  1599. |btree | binary tree | index.bt | static  | -     | none         | yes       |
  1600. +------+-------------+----------+---------+-------+--------------+-----------+
  1601.  
  1602. Those types that have no built in concurrent  access  strat-
  1603. egy,  are  provided  with  fflloocckk(2)  based  file  locking by
  1604. man_db-2.3.x.
  1605.  
  1606. As bbttrreeee is  noticeably  faster  when  doing  mmaann  searches,
  1607. mainly  due  to the fast initialization of the databases, it
  1608. is the preferred library interface.  ccoonnffiigguurree will look for
  1609. bbttrreeee,  ggddbbmm and then finally nnddbbmm routines when configuring
  1610. man_db-2.3.x.
  1611.  
  1612. 66..55..  SShhaarriinngg ddaattaabbaasseess iinn aa hheetteerrooggeenneeoouuss eennvviirroonnmmeenntt
  1613. It may be  necessary  or  advantageous  to  share  databases
  1614. across  platforms,  regardless of the potential file locking
  1615. problems.
  1616.  
  1617. An example would be a user having  a  personal  manual  page
  1618. hierarchy  in  an  NFS  based  home  directory  environment,
  1619. whereby the home directory is held on  and  mounted  from  a
  1620. single machine in a heterogeneous network.
  1621.  
  1622. In  this context, the database cache will have the same name
  1623. and reside in the same place on all machines. There  are  at
  1624. least two ways to deal with this problem.
  1625.  
  1626.  +o Hack  the  _i_n_c_l_u_d_e_/_m_a_n_c_o_n_f_i_g_._h  file  on each platform to
  1627.    provide a  unique  database  name  for  each  system.  No
  1628.    databases will be shared.
  1629.  +o Install  and  use  the  Berkeley  DB  database  interface
  1630.    library on each platform.  These databases can be  shared
  1631.    across   big-endian/little-endian  platforms  although  a
  1632.    database created on a big-endian platform will  suffer  a
  1633.    small  access penalty when used by a litle-endian machine
  1634.    and vice-versa.
  1635.  
  1636.  
  1637.  
  1638.  
  1639. ____________________
  1640.    11 ndbm  databases  are  physically  represented  by  two
  1641. files: _i_n_d_e_x_._d_i_r and _i_n_d_e_x_._p_a_g but are referred to simply as
  1642. _i_n_d_e_x by the interface routines.
  1643.  
  1644.  
  1645.  
  1646.  
  1647.                              2233
  1648.  
  1649.  
  1650.  
  1651.  
  1652.  
  1653.  
  1654.  
  1655. mmaann__ddbb--22..33..xx             mmaannuuaall vv00..55          AApprriill 1188,, 11999955
  1656.  
  1657.  
  1658. 77..  MMiisscceellllaanneeoouuss
  1659.  
  1660. 77..11..  MMooddeess ooff ooppeerraattiioonn
  1661.  
  1662. The man_db utilities can operate in  many  different  modes,
  1663. allowing varying degrees of freedom, functionality and secu-
  1664. rity. No mode requires that the manual page  hierarchies  be
  1665. writable.
  1666.  
  1667. (1) Default mode
  1668.      mmaann  is  setuid to the user MAN_OWNER which is `man' by
  1669.      default and is changeable  via  options  to  ccoonnffiigguurree.
  1670.      mmaannddbb,  if  run  by the superuser or MAN_OWNER, creates
  1671.      globally accessible index databases owned by MAN_OWNER.
  1672.      Once the databases are created, mmaann will update entries
  1673.      in them if it finds newly  installed  manual  pages  or
  1674.      delete   entries  if manual pages are removed.  In this
  1675.      mode it is possible for a malicious mmaann user to  delib-
  1676.      erately  lock a database as a writer, thus denying read
  1677.      access to other users.
  1678.      If cat directories exist and have the  correct  permis-
  1679.      sions,  mmaann  will  take  care  of  producing cat files.
  1680.      These will be owned by MAN_OWNER. The  default  permis-
  1681.      sions of both cat files and databases is 0644.
  1682.  
  1683. (2) No man database updates
  1684.      This  mode  also  requires  mmaann  to  be  setuid, but is
  1685.      favoured where databases must be shared in an  environ-
  1686.      ment  unfriendly to kernel locking procedures, eg. NFS.
  1687.      It also prevents possible `denial of  service'  attacks
  1688.      by malicious mmaann users as mmaann never opens the databases
  1689.      as a writer in this mode.  To replace the functionality
  1690.      lost  by disallowing mmaann write access to the databases,
  1691.      mmaannddbb must be  rerun  whenever  new  manual  pages  are
  1692.      installed.   Failure  to do so will result in mmaann being
  1693.      unable to find  and  display  the  newly  added  manual
  1694.      pages.   As  mmaannddbb lacks the ability to delete database
  1695.      entries for manual pages that have been removed, it  is
  1696.      necessary  to  use  the  ----ccrreeaattee  flag whenever manual
  1697.      pages are removed  from  the  filesystem.   Each  index
  1698.      database  may  be  owned  by an arbitrary user who will
  1699.      have subsequent write  access  to  the  database.   Cat
  1700.      files  are  created  in  the  same  way as for mode (1)
  1701.      above.
  1702.      To  use  the  man_db  utilities  in  this  mode,   edit
  1703.      _i_n_c_l_u_d_e_/_m_a_n_c_o_n_f_i_g_._h    and    comment    out   `#define
  1704.      MAN_DB_UPDATES'
  1705.  
  1706. (3) No man database updates or cat production
  1707.      mmaann is installed not setuid.  This  mode  of  operation
  1708.      probably  offers  the  highest level of security but it
  1709.      requires higher levels of maintenance than other  modes
  1710.      due   to  the  restrictions  imposed  upon  mmaann.   Each
  1711.  
  1712.  
  1713.                              2244
  1714.  
  1715.  
  1716.  
  1717.  
  1718.  
  1719.  
  1720.  
  1721. mmaann__ddbb--22..33..xx             mmaannuuaall vv00..55          AApprriill 1188,, 11999955
  1722.  
  1723.  
  1724.      database is owned by an arbitrary user as in mode  (2).
  1725.      Each  cat  hierarchy is also owned by an arbitrary user
  1726.      who is responsible for creating cat files using  ccaattmmaann
  1727.      whenever  new  manual files are installed.  mmaann will be
  1728.      completely  passive  in  it's  action,  ie.  no   index
  1729.      databases  will be written to and no cat files are ever
  1730.      produced.
  1731.      To use the man_db utilities in this  mode,  supply  the
  1732.      option   `--disable-setuid'   to   ccoonnffiigguurree  and  edit
  1733.      _i_n_c_l_u_d_e_/_m_a_n_c_o_n_f_i_g_._h,    commenting     out     `#define
  1734.      MAN_DB_UPDATES'  and  `#define  MAN_CATS' after running
  1735.      ccoonnffiigguurree.
  1736.  
  1737. (4) Wide open
  1738.      mmaann is installed not setuid.  This mode is  similar  in
  1739.      operation  to  the  majority  of  vendor  supplied, non
  1740.      setuid, cat file supporting manual pager suites. It  is
  1741.      not  recommended.   The databases are owned by an arbi-
  1742.      trary user who maintains them using  mmaannddbb.   mmaann  does
  1743.      not  update  the databases.  Cat files are produced and
  1744.      stored in world writable cat directories and have world
  1745.      write access themselves.
  1746.      To  use  the  man_db utilities in this mode, supply the
  1747.      option   `--disable-setuid'    to    ccoonnffiigguurree,    edit
  1748.      _i_n_c_l_u_d_e_/_m_a_n_c_o_n_f_i_g_._h    and    comment    out   `#define
  1749.      MAN_DB_UPDATES' and change the  definition  of  CATMODE
  1750.      from 0644 to 0666.
  1751.  
  1752. Other  variations  can  also be used. In fact it is possible
  1753. for mmaann to actually create index databases, usually the  job
  1754. of mmaannddbb, for users private manual page hierarchies. This is
  1755. enabled by editing _i_n_c_l_u_d_e_/_m_a_n_c_o_n_f_i_g_._h and un-commenting the
  1756. `/*  #define MAN_DB_CREATES */' line. man_db-2.2 operated in
  1757. this manner.
  1758.  
  1759. In summary, _i_n_c_l_u_d_e_/_m_a_n_c_o_n_f_i_g_._h contains definitions for
  1760.  
  1761.  +o MAN_DB_CREATES
  1762.  +o MAN_DB_UPDATES
  1763.  +o MAN_CATS
  1764.  +o CATMODE
  1765.  +o DBMODE
  1766.  
  1767. and the setuid installation and operation of mmaann is modified
  1768. by supplying either of the following options to ccoonnffiigguurree:
  1769.  
  1770.  +o --enable-setuid=USER
  1771.  +o --disable-setuid
  1772.  
  1773. 77..22..  NNLLSS mmeessssaaggee ccaattaalloogguueess
  1774.  
  1775. man_db-2.3.x  has  built in support for native language mes-
  1776. sage catalogues. That is,  it  can  issue  messages  in  the
  1777.  
  1778.  
  1779.                              2255
  1780.  
  1781.  
  1782.  
  1783.  
  1784.  
  1785.  
  1786.  
  1787. mmaann__ddbb--22..33..xx             mmaannuuaall vv00..55          AApprriill 1188,, 11999955
  1788.  
  1789.  
  1790. locale  of  the  users  choice.  This will only occur if the
  1791. locale's translation has been written. Before undertaking  a
  1792. translation, please contact the author who will be maintain-
  1793. ing a list of such activity.
  1794.  
  1795. Currently, the following translations exist
  1796.  
  1797.  +o *none*
  1798.  
  1799. 77..33..  CCrreeddiittss
  1800.  
  1801. I would like to thank the following people for  their  time,
  1802. effort, support, ideas and code which went into man_db-2.3.x
  1803.  
  1804.     Markus Armbruster <armbru@pond.sub.org>
  1805.     Caleb Epstein <epstein_caleb@jpmorgan.com>
  1806.     Zoltan Hidvegi <hzoli@cs.elte.hu>
  1807.     Nils Magnus <magnus@unix-ag.uni-kl.de>
  1808.     Daniel Quinlan <quinlan@yggdrasil.com>
  1809.  
  1810.  
  1811.  
  1812.  
  1813.  
  1814.  
  1815.  
  1816.  
  1817.  
  1818.  
  1819.  
  1820.  
  1821.  
  1822.  
  1823.  
  1824.  
  1825.  
  1826.  
  1827.  
  1828.  
  1829.  
  1830.  
  1831.  
  1832.  
  1833.  
  1834.  
  1835.  
  1836.  
  1837.  
  1838.  
  1839.  
  1840.  
  1841.  
  1842.  
  1843.  
  1844.  
  1845.                              2266
  1846.  
  1847.  
  1848.  
  1849.  
  1850.  
  1851.  
  1852.  
  1853.  
  1854.  
  1855.  
  1856.                           Glossary
  1857.  
  1858.  
  1859. manual page
  1860.      A file containing descriptions related to the use of  a
  1861.      function  or  program  or  the structure of a file. The
  1862.      name of the file is formed from the title of the manual
  1863.      page  followed  by a period followed by the name of the
  1864.      section that it resides in, optionally followed  by  an
  1865.      extension.  The  format of the file is NNRROOFFFF and may be
  1866.      compressed, having  a  suitable  compression  extension
  1867.      appended.
  1868.  
  1869. cat page
  1870.      A  formatted manual page suitable for viewing in a ter-
  1871.      minal.
  1872.  
  1873. stray cat page
  1874.      A cat page that does not have a relative manual page on
  1875.      the  system,  ie. only the cat page was supplied or the
  1876.      manual page was removed after the  cat  page  had  been
  1877.      created.
  1878.  
  1879. section
  1880.      Each  manual page or cat page hierarchy is divided into
  1881.      sections, each section having it's own directory.  man-
  1882.      ual  page  hierarchy section names begin with `man' and
  1883.      cat page sections with `cat'.
  1884.  
  1885. extension
  1886.      A package may provide manual pages with filenames  end-
  1887.      ing  in  a package-specific extension name. This allows
  1888.      manual pages with the same title to coexist in the same
  1889.      manual  page  hierarchy and section without sharing the
  1890.      same filename.  It also provides  a  further  mechanism
  1891.      for man to select the correct manual page.
  1892.  
  1893. manual page hierarchy
  1894.      A  directory  tree  divided  into manual page sections,
  1895.      each containing a collection of manual pages.
  1896.  
  1897. cat page hierarchy
  1898.      A directory tree divided into cat page  sections,  each
  1899.      containing a collection of cat pages.
  1900.  
  1901. traditional cat page hierarchy
  1902.      The same location as the manual page hierarchy.
  1903.  
  1904. alternate cat page hierarchy
  1905.      A separate location to that of the traditional cat page
  1906.      hierarchy.
  1907.  
  1908.  
  1909.  
  1910.  
  1911.                               ii
  1912.  
  1913.  
  1914.  
  1915.  
  1916.  
  1917.  
  1918.  
  1919.  
  1920.  
  1921.  
  1922. traditional cat page
  1923.      A cat page located in a traditional cat page hierarchy.
  1924.  
  1925. alternate cat page
  1926.      A  cat page located in an alternate cat page hierarchy.
  1927.  
  1928.  
  1929.  
  1930.  
  1931.  
  1932.  
  1933.  
  1934.  
  1935.  
  1936.  
  1937.  
  1938.  
  1939.  
  1940.  
  1941.  
  1942.  
  1943.  
  1944.  
  1945.  
  1946.  
  1947.  
  1948.  
  1949.  
  1950.  
  1951.  
  1952.  
  1953.  
  1954.  
  1955.  
  1956.  
  1957.  
  1958.  
  1959.  
  1960.  
  1961.  
  1962.  
  1963.  
  1964.  
  1965.  
  1966.  
  1967.  
  1968.  
  1969.  
  1970.  
  1971.  
  1972.  
  1973.  
  1974.  
  1975.  
  1976.  
  1977.                              iiii
  1978.  
  1979.  
  1980.  
  1981.  
  1982.  
  1983.  
  1984.  
  1985.  
  1986.  
  1987.  
  1988.                             Contents
  1989.  
  1990.  
  1991. 1.  Introduction ......................................    1
  1992.     1.1  man_db-2.3.x .................................    1
  1993.          1.1.1  The concept ...........................    1
  1994.     1.2  The manual page system .......................    2
  1995.     1.3  Sections of the manual .......................    3
  1996.     1.4  The format of manual pages ...................    3
  1997.     1.5  Arguments to configure .......................    4
  1998.  
  1999. 2.  The specifics of Sections .........................    5
  2000.     2.1  Package specific manual page sections ........    5
  2001.     2.2  Selecting a section type .....................    5
  2002.          2.2.1  Specifying a section ..................    5
  2003.          2.2.2  Specifying an extension ...............    6
  2004.  
  2005. 3.  Filesystem structure ..............................    7
  2006.     3.1  Manual page hierarchies ......................    7
  2007.     3.2  Setting the MANPATH ..........................    7
  2008.     3.3  Other OS's manual pages ......................    8
  2009.     3.4  NLS manual pages .............................    9
  2010.          3.4.1  ISO 8859-1 (latin1) manual pages ......   10
  2011.          3.4.2  Displaying latin1  characters  on  a
  2012.          Linux virtual terminal .......................   10
  2013.          3.4.3  Viewing  ASCII  pages  formatted for
  2014.          latin1 output device .........................   11
  2015.     3.5  Cat pages ....................................   12
  2016.     3.6  Cat page hierarchies .........................   12
  2017.     3.7  Local cat page directory caches ..............   12
  2018.  
  2019. 4.  Compression .......................................   14
  2020.     4.1  Compressed manual pages ......................   14
  2021.     4.2  Compressed cat pages .........................   14
  2022.          4.2.1  Stray cats ............................   15
  2023.  
  2024. 5.  Formatting ........................................   16
  2025.     5.1  GGRROOFFFF ........................................   16
  2026.     5.2  Devices ......................................   16
  2027.     5.3  Macros .......................................   16
  2028.     5.4  Pre-format processors (pre-processors) .......   17
  2029.     5.5  Format scripts ...............................   18
  2030.  
  2031. 6.  The index database caches .........................   19
  2032.     6.1  index database location ......................   19
  2033.          6.1.1  Manual  hierarchies  with  no  index
  2034.          database .....................................   19
  2035.          6.1.2  User manual page hierarchies ..........   19
  2036.     6.2  Contents of an index database ................   19
  2037.          6.2.1  Favouring stray cats ..................   21
  2038.          6.2.2  Accessdb ..............................   21
  2039.          6.2.3  Example database ......................   22
  2040.     6.3  Database types ...............................   22
  2041.  
  2042.  
  2043.                               ii
  2044.  
  2045.  
  2046.  
  2047.  
  2048.  
  2049.  
  2050.  
  2051.  
  2052.  
  2053.  
  2054.     6.4  limitations ..................................   22
  2055.     6.5  Sharing  databases in a heterogeneous envi-
  2056.     ronment ...........................................   23
  2057.  
  2058. 7.  Miscellaneous .....................................   24
  2059.     7.1  Modes of operation ...........................   24
  2060.     7.2  NLS message catalogues .......................   25
  2061.     7.3  Credits ......................................   26
  2062.  
  2063.  
  2064.  
  2065.  
  2066.  
  2067.  
  2068.  
  2069.  
  2070.  
  2071.  
  2072.  
  2073.  
  2074.  
  2075.  
  2076.  
  2077.  
  2078.  
  2079.  
  2080.  
  2081.  
  2082.  
  2083.  
  2084.  
  2085.  
  2086.  
  2087.  
  2088.  
  2089.  
  2090.  
  2091.  
  2092.  
  2093.  
  2094.  
  2095.  
  2096.  
  2097.  
  2098.  
  2099.  
  2100.  
  2101.  
  2102.  
  2103.  
  2104.  
  2105.  
  2106.  
  2107.  
  2108.  
  2109.                              iiii
  2110.  
  2111.  
  2112.  
  2113.